home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / video / vlsetconnection.z / vlsetconnection
Encoding:
Text File  |  1998-10-20  |  11.0 KB  |  199 lines
  1.  
  2.  
  3.  
  4. VVVVLLLLSSSSEEEETTTTCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN((((3333ddddmmmm))))                                      VVVVLLLLSSSSEEEETTTTCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      vlSetConnection - manage the connectivity of a VL path
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////vvvvllll....hhhh>>>>
  13.  
  14.      iiiinnnntttt vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn((((VVVVLLLLSSSSeeeerrrrvvvveeeerrrr ssssvvvvrrrr,,,, VVVVLLLLPPPPaaaatttthhhh ppppaaaatttthhhh,,,,
  15.                          VVVVLLLLNNNNooooddddeeee ssssrrrrccccnnnnooooddddeeee,,,, VVVVLLLLPPPPoooorrrrtttt ssssrrrrccccppppoooorrrrtttt,,,,
  16.                          VVVVLLLLNNNNooooddddeeee ddddrrrrnnnnnnnnooooddddeeee,,,, VVVVLLLLPPPPoooorrrrtttt ddddrrrrnnnnppppoooorrrrtttt,,,,
  17.                          VVVVLLLLBBBBoooooooolllleeeeaaaannnn pppprrrreeeeeeeemmmmpppptttt))));;;;
  18.  
  19.  
  20. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  21.      _s_v_r       Specifies the server handle.
  22.  
  23.      _p_a_t_h      Specifies the path handle.
  24.  
  25.      _s_r_c_n_o_d_e   Specifies the source node.
  26.  
  27.      _s_r_c_p_o_r_t   Specified the port on the source node
  28.  
  29.      _d_r_n_n_o_d_e   Specifies the drain node.
  30.  
  31.      _d_r_n_p_o_r_t   Specifies the port on the drain node
  32.  
  33.      _p_r_e_e_m_p_t   Specifies whether paths may be preempted to establish the
  34.                connection
  35.  
  36. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  37.      vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn establishes a connection from (srcnode, srcport) to
  38.      (drnnode, drnport) on the indicated path. The connection takes effect
  39.      either immediately or at the next vertical interval, depending on the
  40.      video device characteristics. If (srcnode, srcport) is capable of
  41.      multicasting, then any prior targets of (srcnode, srcport) are
  42.      unaffected. Otherwise, the prior targets of (srcnode, srcport) revert to
  43.      default inputs.
  44.  
  45.      Use of vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn is optional in all but the following cases:
  46.  
  47.           The path being setup contains multiple internal nodes.
  48.  
  49.           The connections established by the default routing algorithm are not
  50.           suitable for the application.
  51.  
  52.           A node with multiple ports is used, and the default connections to
  53.           the ports are not suitable for the application.
  54.  
  55.      The specified connection takes effect within the next vertical interval.
  56.      (Note: not all connections may be changed after a path has been setup.
  57.      See the documentation pertaining to each node/device.)
  58.  
  59.      If vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn is not used to explicitly specify the path
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VVVVLLLLSSSSEEEETTTTCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN((((3333ddddmmmm))))                                      VVVVLLLLSSSSEEEETTTTCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      connections, a default routing algorithm is applied when vvvvllllBBBBeeeeggggiiiinnnnTTTTrrrraaaannnnssssffffeeeerrrr
  75.      is called.
  76.  
  77.  
  78. CCCCOOOONNNNTTTTRRRROOOOLLLL UUUUSSSSAAAAGGGGEEEE
  79.      The ability to change or establish connections through vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn is
  80.      dependent on the control usage of the path. Paths with control usage
  81.      VL_DONE_USING may neither set nor query a connection. Paths with control
  82.      usage VL_READ_ONLY may query, but not set, a connection. Paths with
  83.      control usage VL_SHARE may both set and get a connection, but may have
  84.      the connection changed by other paths with control usage VL_SHARE or
  85.      VL_LOCK. Paths with control usage VL_LOCK may set connections and are
  86.      guaranteed not to have the connection changed by any other path.
  87.  
  88.  
  89. SSSSTTTTRRRREEEEAAAAMMMM UUUUSSSSAAAAGGGGEEEE AAAANNNNDDDD PPPPRRRREEEEEEEEMMMMPPPPTTTTIIIIOOOONNNN
  90.      Routing the connection may involve obtaining connectors or other scarce
  91.      resources which paths contend for. If the preempt flag is TRUE, then
  92.      other paths may be preempted in order to route the connection.
  93.      Preemption follows similar rules used for node acquisition during
  94.      SetupPaths. Specifically, a path with stream usage VL_LOCK is never
  95.      preempted. A path with stream usage VL_SHARE may be preempted by any
  96.      other path. Paths with stream usage VL_READ_ONLY are never preempted, as
  97.      by definition they never actually use connectors. (Note, however, that
  98.      paths with control usage VL_SHARE and stream usage VL_READ_ONLY may
  99.      change a connection and thereby cause paths with stream usage VL_SHARE to
  100.      be preempted.)
  101.  
  102.      If preempt is FALSE, or the stream usage level is insufficient to obtain
  103.      required connectors, then VVVVLLLLNNNNooooRRRRoooouuuutttteeee will be returned if the connection
  104.      could not be routed.
  105.  
  106.  
  107. DDDDEEEEFFFFAAAAUUUULLLLTTTT VVVVIIIIDDDDEEEEOOOO CCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNNSSSS
  108.      When a path is first setup, it inherits any connections specified by
  109.      other paths operating on the device. vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn can then be used to
  110.      specify the remaining connections or override the inherited connections.
  111.  
  112.      When vvvvllllBBBBeeeeggggiiiinnnnTTTTrrrraaaannnnssssffffeeeerrrr is called on the path, a default routing algorithm
  113.      will be applied if all drains on the path are unconnected.  This
  114.      maintains compatibility for applications which choose not to explicitly
  115.      set connections:
  116.  
  117.           If there are no internal nodes on the path, then the pixel output of
  118.           the first source node added to the path is connected to the pixel
  119.           input of the first drain node on the path. If the source node is
  120.           capable of multicast, then all drain nodes are connected to the
  121.           source node.
  122.  
  123.           If there is an internal node on the path, then the pixel output of
  124.           the first source node added to the path is connected to the first
  125.           pixel input of the internal node, the pixel output of the second
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. VVVVLLLLSSSSEEEETTTTCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN((((3333ddddmmmm))))                                      VVVVLLLLSSSSEEEETTTTCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.           source added to the path is connected to the second pixel input of
  141.           the internal node, etc. The pixel output of the internal node is
  142.           connected to the first drain node on the path. If the internal node
  143.           is capable of multicast, then all drain nodes are connected to the
  144.           internal node.
  145.  
  146.  
  147. EEEEVVVVEEEENNNNTTTTSSSS
  148.      When a connection is set by vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn,,,, or implicitly by a default
  149.      routing algorithm in vvvvllllBBBBeeeeggggiiiinnnnTTTTrrrraaaannnnssssffffeeeerrrr,,,, a VVVVLLLLSSSSttttrrrreeeeaaaammmmCCCChhhhaaaannnnggggeeeedddd event is sent to
  150.      all paths of an affected target (node, port).  This includes paths using
  151.      the new (node, port) specified in vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn,,,, as well as the prior
  152.      (node, port) targets if their connection to the source was broken (i.e.
  153.      if the source is not capable of multicast)
  154.  
  155.  
  156.  
  157. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  158.      If successful, this functions returns zero. A value of -1 indicates an
  159.      error, and vlErrno is set to one of the following:
  160.  
  161.  
  162.      VVVVLLLLBBBBaaaaddddSSSSeeeerrrrvvvveeeerrrr           The server parameter is not valid.
  163.  
  164.      VVVVLLLLBBBBaaaaddddPPPPaaaatttthhhh             The path is not valid.
  165.  
  166.      VVVVLLLLBBBBaaaaddddNNNNooooddddeeee             The source or target node is not a valid node on
  167.                            the path.
  168.  
  169.      VVVVLLLLBBBBaaaaddddAAAAcccccccceeeessssssss           The path has not been setup, or control usage on
  170.                            the path is is VL_READ_ONLY.
  171.  
  172.      VVVVLLLLBBBBaaaaddddAAAAlllllllloooocccc            A memory allocation attempt failed.
  173.  
  174.      VVVVLLLLNNNNooooRRRRoooouuuutttteeee             The connection could not be routed because
  175.                            connectors or other required hardware resources are
  176.                            in use by other paths that cannot be preempted.
  177.  
  178.      VVVVLLLLPPPPaaaatttthhhhIIIInnnnUUUUsssseeee           The connection could not be routed because another
  179.                            path has the connection locked.
  180.  
  181.      VVVVLLLLNNNNoooottttSSSSuuuuppppppppoooorrrrtttteeeedddd        vvvvllllSSSSeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn is not supported on the device.
  182.  
  183.      VVVVLLLLBBBBaaaaddddIIIImmmmpppplllleeeemmmmeeeennnnttttaaaattttiiiioooonnnn   An internal processing error has occurred.
  184.  
  185. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  186.      vlGetConnection(3dm), vlSetupPaths(3dm), vlBeginTransfer(3dm)
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.